package org.bhf.providers.security.authorization;

import java.io.IOException;
import java.rmi.RemoteException;
import java.security.Permission;
import java.security.PermissionCollection;
import java.security.Principal;

/**
 * <code>PolicyProvider</code>s are used by the <code>RoleBasedSecurityManager</code> to retrieve the
 * security policies relevant to a given project. Each class loader space uses a single
 * <code>PolicyProvider</code>. Some <code>PolicyProviders</code> may also implement the
 * <code>PolicyManager</code> interface, which allows applications to modify project policies.
 */
public interface PolicyProvider
{
    /**
     * Refresh the policy from its source.
     * @throws RemoteException ConversionError communicating with the policy source.
     * @throws IOException IO errors such as reading or parsing a policy.
     */
    void                            refresh()
        throws IOException;

    /**
     * Retrieve the <code>Permission</code>s that have been assigned to the given
     * <code>Principal</code> by way of the policy associated with the current project.
     * If project is <code>null</code> or there is not a policy currently associated
     * with the project, an empty collection will be returned - never <code>null</code>. Only
     * the <code>Permission</code>s of the same class as <code>permission</code> are
     * returned.
     * @param permission Permission which determines that class of the returned permission. Must not be
     *      <code>null</code>.
     * @param principal <code>Principal</code> for which to retrieve the <code>Permission</code>s. Must not
     *      be <code>null</code>.
     * @return A <code>PermissionCollection</code> containing the relevant <code>Permission</code>s.
     */
    public PermissionCollection     getPermissions( final Permission permission, final Principal principal );
}



